package net.matuschek.spider;

/*********************************************
    Copyright (c) 2001 by Daniel Matuschek
 *********************************************/


/**
 * <p>The TaskList is a generic interface for a storage for RobotTask
 * objects. It will be used by the WebRobot for the queue and the list
 * of visited URLs.</p>
 * <p>It implements many methods from the Collection API, but will 
 * only be used to store RobotTask objects.</p>
 * <p>Implementation could store the list in the memory, in a file or
 * even in an SQL database. For lookups it may be useful that the RobotTask
 * implements the hashCode() method.</p>
 * <p><b>Implementations should be thread-safe or must note that they are
 * nopt thread safe !</b></p>
 *
 * @author Daniel Matuschek 
 * @version $Id: TaskList.java,v 1.3 2002/05/31 14:45:56 matuschd Exp $
 */
public interface TaskList {

  /**
   * Add a task to the end of the list
   * @param task a RobotTask object to store in the queue
   */
  void add(RobotTask task);

  /**
   * Add a task at the beginning of list
   * @param task a RobotTask object to store in the queue
   */
  void addAtStart(RobotTask task);


  /**
   * Clean up the list, remove all objects
   */
  void clear();


  /**
   * Is this robot task stored in the list ?
   * @param task a RobotTask object to lookup
   * @return true if there is a RobotTask in the list that is equal to
   * the given task using the equals() method
   */
  boolean contains(RobotTask task);


  /**
   * Remove this object from the list
   * @param task the RobotTaks to remove
   * @return the object was found and removed, false if it
   * was not in the list
   */
  boolean remove(RobotTask task);


  /**
   * Get and remove the first element.
   * @return the first task in the list. This object will also be removed
   * from the list.
   */
  RobotTask removeFirst();

  
  /**
   * Returns the number of elements in this list
   */
  int size();


  /**
   * Get the n-th element in the list. Elements are numbered form 0 to
   * size-1.
   * @param position
   */
  RobotTask elementAt(int position);

}
